Help Text for RISC OS
MoonTool

RISC OS MoonTool, Version 3.24.
Last modified: 05.04.99

Contents

      * Introduction
      * Using MoonTool
      * Moon phases
      * Saving the window positions
      * Selecting a different time/date
      * Test Mode
      * Quitting
      * Options
      * Accuracy
      * Differences between the RISC OS version and the
        original
      * Technical details
      * History (of my versions)
      * Credits
      * Copyright
      * Disclaimer
      * Contact details



Introduction
````````````
MoonTool is a desktop application that calculates and
displays the current phase of the moon and other related
information.

The original version of the program was called "A Moon For
The Sun" since it was written for Sun workstations. Sometime
around 1993 Eduoard Poor ported MoonTool to RISC OS 3.

Later, in early 1999, I saw a request for the moon to appear
the right way up in the program (Eduoard was based in New
Zealand so naturally the moon drawn by his version was the
wrong way up for those of us in the Northern hemisphere).
Also requested was the ability to calculate the moon
phase/information for times other than the current date/time.
Since both these things had been on my list of "Things to get
around to one day" I decided I'd finally get on and do them.

Note that for MoonTool to work correctly the clock in your
computer must be set correctly and your TimeZone/DST must
also be correct. See your RISC OS user guide for more
information.

MoonTool is compatible with RISC OS 3.1 and later.



Using MoonTool
``````````````
MoonTool is run in the normal RISC OS fashion (ie.
double-click on its icon in a filer directory display). There's no
reason why you shouldn't include MoonTool in a boot
sequence (eg. in !Boot.Choices.Boot.Tasks on RiscPCs) if
you're the sort of person who likes having the moon on your
desktop to keep you company. I know that I do.

Initially a small window will open that displays a picture of the
moon as it appears in the sky (although it is always shown
upright). Clicking on the moon in this small 'icon' window will
open the main window which contains various pieces of
information about the date and relative positions of the sun,
moon and earth. Closing the window, or clicking Select on the
Moon graphic, will cause the smaller 'icon' window to be
re-opened.



Moon phases
```````````
Selecting "Moon phases..." from the menu will open a window
containing the dates and times of the quarters of the moon
surrounding the currently selected date/time. The dates/times
shown are all in UTC (Universal Time Coordinated), ie. GMT.

You can also open/close the Moon phases window by clicking
with Adjust on the Moon icon or the Moon in the main
MoonTool window.



Saving the window positions
```````````````````````````
You can save the current positions of the various windows
that MoonTool uses by selecting Save Positions from the
main menu.

When MoonTool is next reloaded it will initially open the
windows in the same place they were when the positions
were saved.

If you want to "clear out" these saved positions you can do so
by deleting the text file !MoonTool.WinPosns. You should do
this if you add/remove the "-h" (half-size) command-line
option in the !Run file. (see later)



Selecting a different time/date
```````````````````````````````
If you select "Choose time..." from the menu a window will
open that allows you to select the date and time of day that
you want MoonTool to use for its calculations.

Note that whilst test-mode is active the Choose Time window
will not work as expected. Rather than following the time
selected test mode will simply 'step' each time a change is
made. It's probably best not to mix the two.

The window contains a number of icons:

Current
      When this option is selected, MoonTool will use the
      current date and time (as obtained from your
      computer's clock) and update its display(s) in real
      time.
      The time adjustment icons will be shaded and
      un-selectable whilst this option is selected.
      Note that this option doesn't have an immediate
      effect. You must click on the "Use" button to cause
      MoonTool to effect it.

Update
      This option, when selected, causes MoonTool to
      update its displays in line with the time showing in the
      time selection window.
      It can sometimes be useful (especially on older/slower
      machines) to turn this option off when selecting a time
      as the calculations MoonTool performs are relatively
      time consuming and so slow things down.
      Note that this option takes immediate effect - you
      don't need to click on "Use".

Bump arrows
      Use these arrows to select the date and time of day
      you're interested in. If you've ticked "Update" then
      MoonTool's various displays will be updated as the
      values are changed.

Now
      Clicking this button causes the current date and time
      to be entered into the time selection window.

Cancel
      Resets whatever options were in force when the time
      selection window was opened. If the button is clicked
      with Select then the window will also be closed.
      Clicking with Adjust keeps the window open.

Use
      Causes MoonTool to use the options (or time/date) in
      the window. As with "Cancel", clicking with Adjust
      rather than Select will cause the window to stay open
      on the screen.




Test Mode
`````````
The original MoonTool had a 'test mode' that rapidly stepped
through time. Later versions (for the Sun/X11) added a button
to (dis)engage this feature at any time. I've added this feature
to my RISC OS version as a menu option and extended it to
allow three different test speeds.

If you select "Test mode" from the menu then test mode will
be engaged at the last selected speed ('Slow' initially). When
test mode is engaged it can be cancelled either by reselecting
it from the menu, or by selecting "Off" from the Test Mode
submenu.

You can simultaneously engage test mode and select a
speed by selecting one from the Test Mode submenu. The
three speeds are (very approximately):

      * Slow, 1 hour per second
      * Fast, 3 hours per second
      * Ludicrous, 1 day per second.




Quitting
````````
The original RISC OS version of MoonTool was quit by
closing its main window. This version should be quit by
selecting "Quit" from its menu (or by quitting it from the Task
Manager's Tasks display, etc).



Options
```````
There are a few user selectable options that can be set by
editing the application's !Run file.

The options are:

Start up 'iconified': -i
      This is set as standard. If for some reason you want
      MoonTool to open its main window at startup (rather
      than the little 'icon' window) then removing the -i
      from the !Run file will make this happen.
      Conversely, replacing the -i will cause MoonTool to
      open the small 'icon' window rather than the main
      window at startup.

Hemisphere: -n or -s
      You can select either Northern or Southern
      hemisphere in the !Run file by including the flags -n
      or -s as appropriate.
      By default, MoonTool assumes Northern hemisphere.

Open phases window at startup: -p
      This flag will cause MoonTool to open the moon
      phases window at start-up.

Start in test mode -t
      This flag causes MoonTool to start up in test mode (at
      the default, ie. slow, speed).

Use the large MoonIcon window: -l
      As of version 3.20, RISC OS MoonTool uses a much
      larger sprite for its Moon-phase display. This sprite
      can also be used in the 'icon' window which will be
      correspondingly larger.
      Because the new sprite is so much larger than the
      original (twice the size, in fact) the normal MoonIcon
      window uses a 'half-size' version to remain a
      reasonable size.
      Should you want the icon window to use the sprite in
      all its unscaled glory, simply add -l to the the !Run
      file in the appropriate place, but note that saved
      window positions file will also need to be removed.

Use outline fonts in the windows: -o
      This flag cuases MoonTool to use outline fonts in its
      windows. Depending on the machine and
      monitor/screen-mode combination you are using you
      may find that outline fonts improve/reduce readability.

Brighten text in the windows: -b
      You may find, especially at large screen sizes, that
      the grey-on-black text in the MoonTool windows is too
      hard to read. The -b option causes MoonTool to
      display all text (that has a black backround) in white
      rather than grey.




Accuracy
````````
To the best of my knowledge the dates and times given by
MoonTool are reasonably accurate. The original
documentation (which is included verbatim as
!MoonTool.!HelpOrig) says that the times should be accurate
to within 10 minutes.

If you feel like checking up on MoonTool there are tables of
moon phases, etc. available on the 'net, for example:

      * Moon Phase times for 1990 - 2005:
      http://aa.usno.navy.mil/AA/data/docs/MoonPhase.html
      * Virtual Reality Moon Phase pictures:
      http://tycho.usno.navy.mil/vphase.html




Differences between the RISC OS version and the original
````````````````````````````````````````````````````````
I've substantially changed the part of MoonTool that
determines the times of the new moons surrounding a given
date (and from these the times of the quarters in between).
This was necessary since the original method could produce
incorrect results, especially when using the time selection
window.

The "ghost moon" drawing is my own interpretation of how
this should be done. I believe that the Sun/X11 versions have
an option to use colour or monochrome when drawing the
moon and show the dark area of the moon in blue. I haven't
bothered with the monochrome option (it doesn't really seem
worth it...) and chosen to make the dark moon look dark. If
you really do want it to be blue, this is possible (see below in
the "techie" section).

The Moon sprites used were obtained by scaling down a
rather nice picture of the full moon I obtained from a PD
source some years ago.



Technical details
`````````````````
The full source code is available as a separate archive. It
should be available from the same place as MoonTool itself,
or failing that from my web pages, or failing that drop me an
e-mail.

It's possible to change the way that the dark moon is drawn
by editing MoonTool's Messages (and possibly Sprites) files.
Specifically, the Messages file contains the definition of the
pixel translation table used to darken pixels in the sprite.

It should also now be possible to create a version of
MoonTool for a different language without having to
re-compile. The Messages and Templates files should now
contain all the language specific words/phrases.



History (of my versions)
````````````````````````
2.00 (19 Feb 1999)

    * My initial release with Northern/Southern hemisphere
      correction, user selectable time and high-resolution
      moon graphics. Still substantially based on Eduoard's
      original port (ie. the version 2.0 referred to in the
      original help text)

3.10 (24 Feb 1999)

    * Updated the core algorithms to the latest ones
      available in the Sun/X11 versions.
    * Re-wrote the Desktop specific code to suit my tastes
      and fit the DeskLib style better.
    * Improved the handling of the time selection window
      considerably and made it into a proper dialog window
      rather than a menu.
    * Added the main menu and Info window.
    * Split the moon phases into an independent window.
      Added code to open this window at startup if
      requested.
    * Closing the main window now "iconifies" the program
      (ie. acts as if the moon button had been clicked).
    * Added code to give (pinboard) iconised windows
      sensible titles.
    * Added Test Speed menu.
    * Re-worked the phase-hunting function to (hopefully!)
      work correctly.

3.11 (16 Mar 1999)

    * Fixed the Julian date as displayed in the main
      MoonTool window (it was 0.5 too high).
    * Fixed a small problem that could cause the
      moon-phases window not to update properly when
      'Current' is re-enabled in the user time window.
    * Added a menu option to save the positions of the
      windows.
    * Changed the layout of the moon phases window to
      make it the same height as the main MoonTool
      window and less 'fussy'.
    * Tweaked the ghost-moon/earth light pixel translation
      table to look better, especially in 256+ colour modes.

3.24 (05 Apr 1999)

    * Redesigned the windows to give a much cleaner and
      more elegant layout. This was prompted by the much
      larger Moon sprite (twice the size of the original).
    * Month names are now displayed abbreviated in all
      windows but the User time window and years are
      displayed in two-digit year format.
    * Tweaked the moon-drawing to pre-calculate some of
      the trig. stuff it uses. This gives a significant
      improvement to the speed of updating the
      moon-phase sprite (with a 132 pixel high sprite the old
      code was *much* too slow).
    * The moon-icon sprite is now created on-the-fly from
      the large sprite. This looks *much* better than just
      letting the Wimp plot the large one at half-size.
    * Added large icon option. This causes the full-size
      moon-phase sprite to be used rather than the
      half-size one.
    * Removed the hemisphere specific sprites - the
      northern hemisphere sprites are now rotated at load
      time if need be. In addition the sprites that are created
      on the fly are now blank in the sprite file to make the
      archive smaller :)
    * Added code to open/close the Phases window when
      the Moon icon is clicked with Adjust.
    * Added interactive help.
    * Workaround for a problem with the Moon: the string of
      'itty-bitty' craters that runs in a vertical line through the
      middle of the sprite looked a mite nasty (they don't
      exactly look good on the real Moon, to be honest) so
      have been de-emphasised to counter the effects of
      the scaling, etc. that the Moon sprite has gone
      through.
    * Added the -b (brighten) and -o (outline fonts) options.



Credits
```````
Designed and implemented by John Walker in December 1987.
Revised and updated in February of 1988.
Revised and updated again in June of 1988 by Ron Hitchens.
Revised and updated yet again in July/August of 1989 by Ron Hitchens.

Original RISC OS port by Edouard Poor, circa 1993.
This RISC OS port by Musus Umbra, 1999.

RISC OS MoonTool was built using DeskLib (the freeware
desktop C library for RISC OS machines).

I'd like to thank the following people for variously suggesting
improvements, offering advice and prompting me to update
the program in the first place: Alan Gray, Reg Hemms,
Raymond Ling, Michael Rozdoba, Graham Jenkins, Fionn
Taylor & Matthew Somerville.



Copyright
`````````
This program is in the public domain: "Do what thou wilt shall
be the whole of the law".

Please leave the original attribution information intact so that
credit and blame may be properly apportioned.



Disclaimer
``````````
The authors cannot and will not be held responsible for any
loss or damage arising from the use of, misuse of, or inability
to use this software.

I am, however, interested in bug reports and feedback and
will do my best to help if you do have problems.



Contact details
```````````````
Musus Umbra, aka Adny:

e-mail: musus@argonet.co.uk
   web: http://www.argonet.co.uk/users/musus/
 snail: c/o 23 Baronsway, Whitkirk, Leeds 15, LS15 7AW, ENGLAND

